Location#

The global Location API provides access to the device’s geographic location, including one-time location retrieval, reverse geocoding, user-driven location selection via map, accuracy control, and permission checking for widgets.

Overview#

This API allows you to:

• Request the device's current location
• Select a location manually using a map interface
• Reverse geocode latitude and longitude to address details
• Adjust location accuracy settings
• Check location access status for widgets

Note: This is a global API and does not require import.

API Reference#

Location.isAuthorizedForWidgetUpdates(): Promise<boolean>#

Checks whether widgets have permission to receive location updates.

1const isAuthorized = await Location.isAuthorizedForWidgetUpdates()
2if (!isAuthorized) {
3  console.log("Widget location access is not authorized.")
4}

Location.setAccuracy(accuracy: LocationAccuracy): Promise<void>#

Sets the desired accuracy level for location retrieval. Higher accuracy may increase battery usage and wait time.

Parameters#

1await Location.setAccuracy("hundredMeters")

Location.requestCurrent(options?: { forceRequest?: boolean }): Promise<LocationInfo | null>#

Requests the user's current location once. May trigger a permission prompt if not previously granted.

By default, if a cached location is available, it will be returned immediately. If no cached location exists, a new request will be made. To force a new location retrieval even if a cached value exists, pass { forceRequest: true }.

Parameters#

1const location = await Location.requestCurrent({ forceRequest: true })
2if (location) {
3  console.log("Latitude:", location.latitude)
4  console.log("Longitude:", location.longitude)
5  console.log("Timestamp:", location.timestamp)
6}

Location.pickFromMap(): Promise<LocationInfo | null>#

Opens the built-in map interface to allow the user to manually select a location.

1const selected = await Location.pickFromMap()
2if (selected) {
3  console.log("User selected:", selected.latitude, selected.longitude)
4}

Location.reverseGeocode(options): Promise<LocationPlacemark[] | null>#

Converts latitude and longitude into human-readable place information such as street, city, and country.

Parameters#

1const placemarks = await Location.reverseGeocode({
2  latitude: 51.5074,
3  longitude: -0.1278,
4  locale: "en-GB"
5})
6
7if (placemarks?.length) {
8  const place = placemarks[0]
9  console.log("City:", place.locality)
10  console.log("Country:", place.country)
11}

Types#

LocationAccuracy#

Specifies the desired accuracy of location data:

1type LocationAccuracy =
2  | "best"
3  | "tenMeters"
4  | "hundredMeters"
5  | "kilometer"
6  | "threeKilometers"

LocationInfo#

Represents a geographic coordinate with timestamp:

1type LocationInfo = {
2  /**
3   * The latitude in degrees.
4   */
5  latitude: number
6  /**
7   * The longitude in degrees.
8   */
9  longitude: number
10  /**
11   * Timestamp of when the location was recorded, in milliseconds since epoch.
12   */
13  timestamp: number
14}

LocationPlacemark#

Represents a human-readable description of a geographic coordinate, typically returned by reverse geocoding. Includes structured location details such as city, country, and street.

1type LocationPlacemark = {
2  location?: LocationInfo
3  region?: string
4  timeZone?: string
5  name?: string
6  thoroughfare?: string
7  subThoroughfare?: string
8  locality?: string
9  subLocality?: string
10  administrativeArea?: string
11  subAdministrativeArea?: string
12  postalCode?: string
13  isoCountryCode?: string
14  country?: string
15  inlandWater?: string
16  ocean?: string
17  areasOfInterest?: string[]
18}

Field Descriptions#

Example Usage#

Reverse Geocode#

1const placemarks = await Location.reverseGeocode({
2  latitude: 40.7128,
3  longitude: -74.0060,
4  locale: "en-US"
5})
6
7if (placemarks?.length) {
8  const place = placemarks[0]
9  console.log("Country:", place.country)
10  console.log("City:", place.locality)
11  console.log("Street:", place.thoroughfare, place.subThoroughfare)
12  console.log("Full Name:", place.name)
13  console.log("Postal Code:", place.postalCode)
14  console.log("Points of Interest:", place.areasOfInterest?.join(", "))
15}

Address Formatter (Helper)#

1function formatAddress(p: LocationPlacemark): string {
2  return [
3    p.country,
4    p.administrativeArea,
5    p.locality,
6    p.subLocality,
7    p.thoroughfare,
8    p.subThoroughfare
9  ].filter(Boolean).join(", ")
10}

Best Practices & Use Cases#

• Use areasOfInterest and name to display user-friendly place names.
• Use postalCode, locality, and administrativeArea for autofill and geotagging.
• Use timestamp to determine freshness of location data.
• Use timeZone for localizing time-based features.
• Set location accuracy before calling requestCurrent for optimal precision.
• Always check widget permissions via isAuthorizedForWidgetUpdates().

Notes#

• Reverse geocoding may return multiple results. Use the first placemark for best relevance.
• If location retrieval fails, null is returned.
• When forceRequest is false or omitted, cached location may be used for faster results.
• In widgets, location access may be restricted. Always verify permissions explicitly.